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Preface 

About This Manual 


This manual provides the specifications of to the Cortland Tools for the application 
programmer. It defines the terms used in describing the tools and provides 
background information. . 









Roadmap to the 
Cortland Technical Manuals 

The Cortland has many advanced features, making it more complex than earlier 
models of the Apple II. To describe it iully, Apple has produced a whole suite of 
technical manuals. The manuals are listed in Table A-l. Figure A-l is a diagram 
showing the relationships among the different manuals. Depending on the way you 
intend to use the Cortland, you may need to refer to a select few of the manuals, or 
you may need to refer to most of them. 


Table A-l. The Cortland Technical Manuals 
Title 

Technical Introduction to the Cortland 

Cortland Hardware Reference 

Cortland Firmware Reference 

Writing Cortland Programs 

Cortland Toolbox Reference: Volume I 

Cortland Toolbox Reference: Volume II 

Cortland Programmer's Workshop 

Cortland Workshop Assembly Language Reference* 

Cortland Workshop C Reference* 

Cortland Workshop Pascal Reference* 

ProDOS/8 Technical Reference 

Cortland Operating System Reference 

Human Interface Guidelines 

Apple Numerics Manual 

There is a Pocket Reference for each of these. 


Subject 

what the Cortland is 
machine internals—hardware 
machine internals—firmware 
sample program using the toolbox 
toolbox specifications 
more toolbox specifications 
the development environment 
using assembly language 
using C on the Cortland 
using Pascal on the Cortland 
ProDOS for Apple II programs 
ProDOS and loader for Cortland 
for ail Apple computers 
numerics for aU Apple computers 
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The Technical Introduction 

text 

The Technical Introduction to the Cortland, tells a little about a lot of things, but it 
doesn't tell everything about anything. To find out ail about any one as pea of the 
Cortland, you should read a specific technical manual. To find out which one, read 
on. 


The Machine Reference Manuals 

The Cortland Hardware Reference and the Cortland Firmware Reference contain 
information about the machine itself. You don't need to read these manuals to be 
able to develop applications for the Cortland, but they will give you a better 
understanding of the machine's features. They will also provide the reasons why 
some of those features work the way they do. 


The Tooibox Manuals 

Like the Macintosh, the Cortland has a built-in tooibox that can be called by 
applications. The toolbox serves two purposes: it makes developing new 
applications easier, and it supports the desktop user interface. 

When you first start using the tooibox, Writing Cortland Programs provides the 
recommendations and guidelines you need It is not a complete course in 
programming for the Cortland; rather, it is a starting point. It explains the Cortland 
tools and describes an event-driven program. It includes a simple example of such a 
program that uses the Cortland tools, and demonstrates the way you use the Cortland 
Programmer's Workshop to develop the program. 

For detailed specifications of the tool calls, you'll need both volumes making up the 
Cortland TooLBox Reference. 


The Cortland Programming Languages 

The Cortland does not restrict developers to a single programming language. Apple 
is currently providing an assembler and compilers for C and Pascal. Other 
compilers can be used with the workshop, provided that they observe the standards 
Apple has set up. 




There is a separate reference manual for each programming language on the 
Cortland The manuals for the languages Apple provides are the Cortland 
Assembler Reference, the Cortland C Compiler Reference, and the Cortland Pascal 
Compiler Reference . 


The Programmer $ Workshop Manual 

The core of the development environment on the Cortland is the Cortland 
Programmer's Workshop, also allied CPW. CPW is a set of programs that enable 
developers to create and debug application programs on the Cortland The manual 
that describes CPW is the Cortland Programmer’s Workshop manual. It includes 
information about the parts of the workshop that all developers will use, regardless 
which programming language they use: the shell, the editor, the linker, the 
debugger, and the utilities. 


What About FroDOS? 

ProDOS on the Cortland comes in two flavors: one for compatibility with the models 
of Apple n that use 8-bit CPUs, called ProDOS/8, and one that utilizes the full power 
of the Cortland, ProDOS/l6. Those two versions of ProDOS are described in their 
own manuals, ProDOS/8 Technical Reference and ProDOS/16 Technical Reference 


AIl-Appte Manuals 

In addition to the Cortland manuals mentioned above, there are two manuals that 
apply to all Apple computers. Those are Human Interface Guidelines and Apple 
Numerics Manual. 


How to use this book 

If you are planning on simply using the Cortland Tools that Apple provides, 
Chapters 1 and 2, along with the specifications for the individual tools and routines, 
will provide you with enough information. If you are planning on developing your 
own tools, you will need to read Appendix A. 






What this manual contains 

This manual contains the following chapters: 

i About this manual tells you about this manual. 

■ Chapter 1, Introducing the Tools, defines the terms used in this manual and 
summarizes the capabilities of the Tools. 

i Chapter 2, Calling the Apple Tools, describes how to call the tools from 
assembly language, C, and Pascal, describes how to pass parameters, and 
indicates how errors are signaled 

m The rest of the chapters describe the individual tools, one to a chapter. Ail of 
the routines available for the tool are included in its appropriate chapter. 

a Appendix A provides the information needed to write your own tool set, and 
Appendix B summarizes ail tool error codes for quick reference. 


Visual Cues 

(Not yet decided for Grand Design manuals.) 


Other Reference Material You’ll Need 

(TBD) 


Language Notation 

(Still being hotly debated.) 












Table of Contents 


Chapter 1 Introducing The Tools 

What is a Tool? 

What can the Tools do for me? 

Are there any limitations? 

What kinds of Apple Tools are there? 

Integer Math Tools 
Event Manager 
Menu Manager 
Miscellaneous Tools 
QuickDraw II 
SANE Tools 
Sound Manager 
Tool Locator 
Window Manager 

Chapter 2 Using the Apple Tools 

Initializing Tools at application start-up 
Calling the correa routine 

Calling a routine from assembly language 
Calling a routine from Pascal 
Calling a routine from C 






Passing Parameters 
Return from the call 

Hags and registers 
Error handling 

Chapter 3 Event Manager 
Overview 
Event Types 

Mouse Events 
Keyboard Events 
Window Events 
Other Events 
Event Priority 
Event Records 

Event Code 
Event Message 
Modifier Hags 
Event Masks 

Using the Event Manager 

Responding to mouse events 
Responding to keyboard events 
Responding to window events 
Responding to other events 
Posting and removing events 
Other operations 
Using alternative pointing devices 
Installing device drivers 
Removing device drivers 
The journaling mechanism 
RMBootlnit 





EMStartUp 

EMShutDown 

EMVersion 

EMReset 

EMActive 

Do Windows 

GetNextEvent 

EventAvail 

GeLMouse 

Button 

StillDown 

WaitMouseUp 

PostEvent 

FlushEvents 

GetOSEvent 

OSEventAvail 

TickGount 

GetDBITime 

GetCaretTime 

SetSwitch 

SetEventMask 

FakeMouse 

Event Mamger Error Codes 

Chapter 4 Integer Math Tools 

(The rest of the tool chapters will be carried out to the same level of detail as the 

Event Manager) 




Chapter S Memory Manager 


Chapter 6 Menu Manager 

Chapter 7 Miscellaneous Tools 

Chapters QuickDrawII 

Chapter 9 SANE 

Chapter 10 Sound Manager 

Chapter 11 Text Tools 

Chapter 12 Tool Locator 

Chapter 12 Window Manager 

Appendix A Writing your own tool set 


Appendix 8 IrTor Codes 



Chapter 1 


Introducing the Tools 


AJpho Draft 6/10/86 













What is a Tool? 

A software Tool" or ‘Tool Set", in the Cortland environment, is a collection of 
related routines (or functions) that provides one major capability. Each routine 
performs a fundamental operation and converts zero or more inputs to zero or more 
outputs and side effects. For example, the QuickDraw II Tool provides routines that 
handle graphics on the Cortland Within that tool, PenSize and PenMode are 
functions that set the pen size and pen mode. 

The tools, then, are routines that are always available to perform many common 
tasks. If you are familiar with Macintosh programming, this concept is similar to the 
Macintosh Toolbox. In the Cordand implementadon, the concept is even more 
important. Many of the capabilides of the Cordand. are easily accessed through the 
tools. For example, even the Memory and Event Managers are considered to be 
tools on the Cordand, ("Manager", by the way, is simply another name for a 
collection of routines. Some of the tool sets are called "xxx Tools", others are called 
"xyz Manager", with the names assigned merely by convention). 


What Can the Tools Do For Me? 

The tools provide powerful capabilides that allow an application to concentrate on 
its specific business rather than on the background work . 

A number of the tools are included in ROM. This approach makes those tools 
available to all programs without using disk space. Addidonal tools are available in 
RAM. However, you don't need to keep track of where a particular function is or 
even if it is in ROM or RAM. A tool called the Tool Locator, which allows tools and 
appiicadons to communicate, takes care of the necessary bookkeeping functions. 

The Tool Locator fires up when the Cordand is turned on, and thereafter does its work 
behind the scenes. You won't even need to call the Tool Locator if you are simply 
using the Apple tools in your application. To use the tools in the simplest fashion, 
you don't need to know anything but the name for the tool and how to call it from the 
appropriate programming language. (Calling informadon is in Chapter 2.) 

The tools thus provide their capabilities at a minimum cost*, their bookkeeping 
functions are almost automatic, the interface to them is simple, and the applications 
you write will not be rendered obsolete by any future changes to the hardware. 

The Tool Locator is also flexible enough to allow you to extend the scope of the tools 
by writing your own, and powerful enough to keep track of both the Apple tools and 
your tools. You can write and install your own tools if you wish, and still have the 
Apple tools available when needed 
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The Cortland tools are independent of the operating system being used. They are 
thus available for any Cortland application, whether the application is running under 
ProDOS, Pascal, or another operating system. 


Are There Any Limitations? 

There is at least one important point to consider when you are planning to call a 
Cortland tool from your application: the tools are designed to run in "full native" 
mode, rather than in Apple n emulation mode. In full native mode, the e, m, and x 
bits registers are all set to 0, which provides native mode, a 16-bit accumulator, and 
16-bit index registers. Almost all of the tools require this mode, and simply will not 
work if the machine is in any other state. The limited exceptions to this rule are 
documented under the individual calls described in later chapters in this manual. 


0*® Are there any other factors that should be mentioned? Should I warn them away 
from hybrid applications and the tools? ***) 


What Kinds of Apple Tools Are There? 

In this section, we simply list the tool sets, the categories within the tool sets, and a 
brief summary of some their capabilities. The listing does not contain definitions of 
the calls; for a summary of the routines available for a given tool, look at the first 
page of the chapter describing the tool. For an individual routine, look it up in the 
index and under its appropriate tool 

We recognize that a summary such as this can seem like teasing; in fact, that's some of 
the point! The Cortland toolbox is so large that we wish to introduce you to their 
entire range and encourage you to use as many of them as possible. 

Every tool set or manager has a class of routines known as "Standard Housekeeping 
Routines". These routines allow the tool set to be dealt with as a Cortland tool set. 
Included among the routines are boot initialization and application startup calls, an 
application shutdown call,a reset call, and a call which rerums the version number of 
the particular tool and status. Whether or not a particular type of these standard calls 
is used varies from tool set to tool set; however, ail of the routines must be present in 
each tool set. 
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Integer Math Tools 


These routines support multiplication and division of several types of numbers, and 
also convert numbers from one type to another. The types of numbers dealt with are 
as follows: 

ii Integers, which are single word signed integers 
b Long integers, which are two-word signed integers 
b Fixed, which are two-word signed values with 16 bits of fraction 
i Frac, which are two-word signed values with 30 bits of fraction 


Moth Routines 

These routines support multiplication and division of integer, long integer, Fixed, 
and Frac numbers. 


Conversion Routines 

These routines convert between a binary value and an ASCII character string 
representing that value. The binary value can be either a 2-byte integer or a 4-byte 
integer. The character string can be in either hexadecimal or decimal format. 

The routines allow you to: 

m Convert integers to hex, long, or decimal format ASCII strings, 
ii Convert longs to decimal format ASCII strings. 
m Convert hex ASCII strings to integer or long. 

® Convert decimal format ASCII strings to integers or longs. 


Event Manager 


Toolbox Event Manager routines 

These routines check events to see if they are of interest to the application. If the 
events are of interest, and the Desk Manager doesn't want them, the routines return 
with the event. 
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Mouse reading routines 

These routines provide the ability to read the status of the mouse. 


Posting and Removing Events 

These routines allow you to place or remove events into the event queue. 

Accessing Events Routines: 

These routines check events to see if they are of interest to the application. If the 
events are of interest, the routines return with the event. 


Miscellaneous Event Manager Routines: 

These routines allow you to: 

■ Check the number of ticksfsixtieths of a second) since the system last started up. 

a Return suggested maximum difference of ticks which determines a double 
mouse-dick.. 

a Return the number of ticks between blinks of the caret marking the insertion 
point. 


Menu Manager 

(Writer's note: this is a RAM tool and is still changing shape. Summary will be in 
next draft.) 


Miscellaneous Tools 

The miscellaneous tools are a collection of various routines. Their capabilities are 
summarized below. 

lottery RAM Routines 

These routines allow you to: 

■ Write or read data to or from the Battery RAM. 

■ Write or read data to or from a specified Battery RAM parameter. 
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Clock Routines 

These routines allow you to set or get the current time. 

Vector Initialization Routines 

These routines allow you to set or get the vector address for a specified interrupt 
manager or handler. 


HeartSeot Routines 

These routines allow you to: 

n Install or delete a specified task into or out of the HeartJBeat Interrupt Service 
queue. 

m Remove ail tasks from the Heartbeat Interrupt Service queue. 

System Death Manager 

This routine allows you to control the System Death Manager. 

Get Address Tool 

This routine allows you to determine the address of a parameter referenced by the 
firmware. 


Mouse Routines 

These routines allow you to: 

i Initialize, set, position, home, and read the values for the mouse. 

ii Set and get the damp values for the mouse, 
m Return the interrupt status for the mouse. 

ID Tag Manager Routines 

These routines allow you to: 

i Create and delete ID tags used for memory management. 

■ Return the status of a given ED tag. 
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Interrupt Control 

This routine allows you to enable or disable certain interrupt sources. 

Firmware Entry 

This routine allows you to use some Apple]! emulation mode entry points. 

Tick Counter 

This routine returns with the current value of the tick counter. 

Packing and Munging Tools 

These routines allow you to: 

n Pack bytes into, and unpack bytes from, a special format which uses less storage 
space. 

n Manipulate bytes in a string of bytes. 

Interrupt inabte Siate 

This routine returns with certain hardware interrupt enable states. 

Absolute Clomp Routines 

These routines set and get the current values of the absolute device damps. 


QuickDraw II 

QuickDraw II is the graphics handler for the Cortland. Since many of the other 
Cordand Tools depend on QuickDraw n (the Window Manager, for example), the 
QuickDraw calls will be used by virtually every application. 

There are several categories of QuickDraw n calls, as discussed in the following 
sections. 


1-6 


Alpha Draff 6/10/86 






Global environment routines 

These routines set up the graphics environment for QuickDraw EE and the other tools. 
Included are calls which: 

m Specify ("Set") or return ("Get") the settings for the scan line bytes, the color 
tables, and the entries in the color tables. 

m Set or get the setting for the system font. 

m Set or get the setting for the maximum width or size of buffers dealing with text 
i Clear the screea 

n Turn Super Hi-Res Graphics mode on or off. 

GrofPort routines 

These routines set up the GrafPort for QuickDraw U and the other tools. Included are 
calls which: 

m Open, initialize, and dose a GrafPort 
m Set or get the current Grafport or the GrafPort's location, 
m Set, get, change the size, adjust the.origin, or move the GrafPort's PortRect 
m Set, get, or change the current dip regions. 

i Hide or show the pen, and set or get the current values for the state, size,mode, 
pattem;and mask for the pen. 

m Set or get the background pattern. 

m Move the current pen location to a point or a relative distance. 

m Set or get the current font, the font flags, the font globals, and other font 
information. 

■ Set or get the text face and mode. 

in Set or get the space and char extra fields. 
m Set or get the foreground and background colors. 

■ Set or get the ClipRgn, VisRgn, and VisHandie. 
n Set or get the GrafProcs record 

Drawing routines 

These calls allow you to: 

m Draw a line from the current pen position to either a spedfied point or a 
relative distance. 
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a Frame, paint, erase, invert, or fill rectangles, regions, polygons, ovals, round 
rectangles, and arcs. 

Pixel transfer routines 

These routines allow you to scroll or shift a region of pixels. 

Text drawing and measuring routines 

These routines allow you to: 

■ Draw a character, text, string, or c-string. 

■ Get the width of a character, text, string, or c-string. 

■ Fill a rectangle with a character, text, string, or c-string. 

Calculations with rectangles 

These routines allow you to: 

m Set the dimensions of a rectangle. 

■ Offset or inset a rectangle. 

a Calculate the intersection of two rectangles and place the intersection in a third 
rectangle. 

■ Calculate the union of two rectangles and place the union in a third rectangle. 

■ Determine whether a point is in a particular rectangle, or copy points to the 
upper left and lower rignt of a rectangle. 

■ Determine whether two rectangles are equal. 

■ Determine whether a rectangle is empty. 

Calculations with points 

These routines allow you to: 

■ Add two points together, or subtract a point from another point. 

■ Set a point to specified values. 

■ Determine whether two points are equal. 

■ Convert a point from local to global coordinates, and visa versa. 
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Calculations with regions 

These routines allow you to: 

i Create a new region, or dispose of a region. 

■ Copy contents from one region to another, 
i Empty or overwrite a region. 

i Open or dose a temporary region, 
a Offset or inset a region. 

m Calculate the union of two regions and place the union in a third region. 

a Calculate the intersection of two regions and place the intersection in a third 
region. 

m Calculate the difference between two regions and place the difference in a third 
region. 

m Calculate the difference between the union and the intersection of two regions 
and place the result in a third region. 

m Determine whether a point is in a particular region, 
a Determine whether a rectangle intersects a particular region. 
m Determine whether two regions are equal 
m Determine whether a region is empty, 

Calculations with polygons 

These routines allow you to open^ dose, dispose of, or offset a polygon. 

Mopping and scaling utilities 

These routines allow you to: 

b Map points, rectangles, and regions from a source to a destination. 

■ Scale points from a source to a destination. 

Miscellaneous utilities 

These routines allow you: 

■ Return a pseudorandom number. 

is Set a seed value for a random number generator, 
i Get the values for a specified pixel. 
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Customizing QuickDraw operations 

These routines are similar to their Macintosh counterparts. They allow you to: 
Set up a standard Proc record. 

Draw standard text, lines, rectangles, round rectangles, ovals, arcs, polygons, 
regions, and pixels. 

Make standard comments for pictures. 

Do standard text measuring. 

Do standard storage and retrieval from the text record 
TeU QuickDraw not to use scan line interrupts. 

Get the address of a screen table and two conversion tables. 

Cursor-handling routines 

These routines allow you: 

■ Initialize the cursor. 

■ Set or get the current settings for the cursor, 
i Show or hide the cursor. 

a Obscure the cursor. 
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Sane Tools 

The ROM Tools for the Cortland will provide all of the functions found in the 
Standard Apple Numeric Environment (SANE). The SANE Tools can be called by 
using the normal call mechanism. For more information regarding the capabilities 
of SANE, refer to the Apple Numerics Manual . 


Sound Manager 

The Sound Manager controls sound generation for the Cortland, particularly for the 
Digital Oscillator Chip (DOC). There are two groups of calls in the manager; the 
tool calls and some low-level routines designed for fast access. 


Sound Tool Colls 

These routines allow you to: 

m Write and read a specified number of bytes from and to DOC RAM. 
a Set and get the volume for a sound generator, or change the system volume. 
m Stan or stop the sound for a particular generator, 
i Return the status of a spedfed generator, or the status of all generators, 
n Set up the entry points for the system and user sound interrupt handler 
a Return the current Free Form synthesizer sound-playing status, 
a Return the jump table address for the low-level routines 

low-level Sound Routines 

These routines, designed for quick access, allow you to: 
a Write and read any register within the DOC. 
a Write and read a specified Ensoniq RAM location, 
a Write and read the next DOC or RAM location. 


Tool Locator 

The Tool Locator provides the magic that allows the Cortland Tools to function. 
You'll only need to use it if you are writing your own Tool Set to supplement the Apple 
Cortland Tools. 
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The functions provided by this tool set get and set the Tool Set Pointers, Function 
Pointers, and Work Area Pointers all of the Tools need. For the other toois, the Tool 
Locator provides these functions automatically. 


Window Manager 

(Writer's note: this is a RAM tool and is still changing shape. Summary and details 
will be in next draft) 
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Initializing Tools At Application Start-Up 

There will be a simple mechanism for asking for the correct tools when the 
application starts. However, design of the mechanism is not yet complete. 


Calling the Correct Routine 

The Apple Tools are available from 65816 assembly language, ???? Pascal, and 
Cortland Workshop C. The general rules for accessing the Tools are outlined in the 
following sections. 


Calling a Routine From Assembly Language 

We have provided macros in order to make calling a routine as simple as possible. 
You make an assembly-language call as follows: 

1. If the function has any output, push room for it on the stack. 

2. Push the inputs in the specified order listed.. 

3. Invoke the appropriate macro by entering the name of the routine. 

4 . Pull the output, if any, from the top of the stack. 

The input and output parameters for each call are provided in the descriptions of 
each individual call in this manual and in the Cortland Toolbox Reference: Volume 
U (not yet available). 


Calling a Routine From Pascal 

(^Writer's note: the information in this section is pure conjecture, based on the 
information available for C, since Pascal remains in Umbo.^®) 

The interface libraries which allow the Cord and tools to be accessed from the Pascal 
programming language are included in Cortland Workshop^Pascal. Those libraries 
contain the function and procedure definitions for the tools. The steps to use a 
particular routine are as follows: 

1. Make the routine accessible by providing a USES statement which indudes the 
appropriate file (for example, TUTR for a Quickdraw n calD. The file will provide 
the function and procedure dedaradons. 

2. Invoke the call by entering its name and supplying the correct parameters. 
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The names of the USES files and the parameters for each routine are described in the 
individual routine descriptions in this manual and in the Cortland Toolbox 
Reference: Volume H (not yet available). 


Calling a Routine From C 

The interface libraries which allow the Cortland tools to be accessed from the C 
programming language are included in Cortland Workshop C Those libraries 
contain the function definitions for the tools. The steps to use a particular routine are 
as follows: 

1. Make the routine accessible by using an #include statement which includes the 
appropriate file (for example, quickdraw.h for a Quick draw II call). The included 
file will provide the function declarations. 

2. Invoke the call by entering its name and supplying the correct parameters. 

The names of the #include files and the parameters for each routine are described 
in the individual routine descriptions in this manual and in the Cortland Toolbox 
Reference: Volume 11 (not yet available). (^“Writer's note: the libraries and 
function calls were not available soon enough to include in this draft*® 4 ) 


Passing Parameters 

Most input and output parameters to the tool calls are passed on the stack, with some 
occasional exceptions. The parameters and parameter-passing method are defined 
by each routine. Usually, the parameters are passed on the stack, with the routine 
pulling input parameters off and leaving any output parameters on the stack for the 
calling program to handle. The method and parameters for each routine is 
described under the routine in the chapters which describe specific Tool Sets. 


Return From the Call 

Upon completion of the call, the routine returns control directly back to the 
application. The following sections describe the state of the flags and registers upon 
return from a tool call and the way that errors are returned from the call. 


Flags and Registers 

The state of all flags and registers upon return from a tool call is summarized in the 
following table: 
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Table X-X: Flags and R®glst®rs on B®tum From a Call 


N flag 

V 

m 

x 

D 

I 

Z 

C 

E 


As set by routine 
As set by routine 
Unchanged (must be 0) 

Unchanged (must be 0) 

Set to 0 
Unchanged 
As set by routine 

As set by routine, or error flag (see next section) 
Unchanged (must be 0) 


A register As set by routine or A®0 successful call, A^O error code (see next section) 

X As set by routine 

Y As set by routine 

S Parameters have been removed from stack 

D Unchanged 

P See list of flags above 

DB Unchanged 

PB Unchanged 

PC Address following call 


Note that '’unchanged" means that the value is the same as it was just before the function call. 


Error Handling 

Some tools can return errors on some routines. If they do, the convention is that the 
cany flag (C flag) is set to 1 if an error occured, and the A register contains the error 
code. The error code has the following format: 

High Byte Low Byte 

Tool Set Number Message Number 

With this method, an error can be properly identified even if it occurs during one 
tool set's call, but doesn't aoually show up until a call from another tool set. For 
example, using this method, a QuickDraw n call can pass on an error message from 
the Memory Manager. 

The error codes for an individual Tool Set are listed at the back of its chapter,- and all 
error codes are summarized in Appendix B. 

Error codesSOOO 1 -$000F are reserved for use by the function dispatcher. Remaining 
error codes are defined by each tool set. 
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